/*
 * 健康检查控制器
 * 位于包：org.example.lethear.controller
 * 
 * 这个控制器提供系统健康状态检查接口，主要用于：
 * 1. 应用程序健康状态监控
 * 2. 负载均衡器健康检查
 * 3. 容器编排系统的健康探针
 * 4. 运维监控系统的状态查询
 * 
 * 这些接口通常被以下系统调用：
 * - Kubernetes的健康探针（liveness probe / readiness probe）
 * - 负载均衡器的健康检查
 * - 监控系统（如Prometheus、Zabbix）
 * - 自动化部署系统
 * 
 * 所有接口都是公开的，不需要认证。
 */
package org.example.lethear.controller;

import org.example.lethear.utils.Result;
import org.springframework.security.access.prepost.PreAuthorize;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.time.LocalDateTime;
import java.util.HashMap;
import java.util.Map;

/**
 * 健康检查控制器
 * 
 * @RestController - 标识这是一个REST控制器，返回JSON格式数据
 * @RequestMapping - 指定控制器的基础URL路径（空字符串表示根路径）
 */
@RestController
@RequestMapping
public class HealthController {
    
    /**
     * 系统健康检查接口
     * 
     * 这是主要的健康检查接口，返回系统的运行状态信息：
     * - 系统状态（UP/DOWN）
     * - 当前时间戳
     * - 服务名称
     * - 版本信息
     * 
     * 这个接口通常用于：
     * - 负载均衡器判断服务是否可用
     * - 容器编排系统的健康检查
     * - 监控系统的状态查询
     * 
     * @return Result<Map<String, Object>> 健康状态信息
     */
    @GetMapping("/health")
    @PreAuthorize("permitAll()")  // 允许所有用户访问，无需认证
    public Result<Map<String, Object>> health() {
        // 1. 创建健康状态数据映射
        Map<String, Object> data = new HashMap<>();
        
        // 2. 设置系统状态
        // "UP"表示系统正常运行，"DOWN"表示系统故障
        data.put("status", "UP");
        
        // 3. 设置当前时间戳
        // 用于判断服务是否响应及时
        data.put("timestamp", LocalDateTime.now());
        
        // 4. 设置服务名称
        // 用于标识具体的服务实例
        data.put("service", "LetHear Backend");
        
        // 5. 设置版本信息
        // 用于版本管理和问题排查
        data.put("version", "1.0.0");
        
        // 6. 返回成功响应
        return Result.success("系统运行正常", data);
    }
    
    /**
     * 简化的状态检查接口
     * 
     * 这是一个更简单的健康检查接口，只返回基本的状态信息。
     * 适用于对响应时间要求较高的场景，如：
     * - 高频率的健康检查
     * - 轻量级的监控探针
     * - 快速的服务可用性判断
     * 
     * @return Result<String> 服务状态信息
     */
    @GetMapping("/status")
    @PreAuthorize("permitAll()")  // 允许所有用户访问，无需认证
    public Result<String> status() {
        // 1. 返回简单的状态信息
        // 这个接口主要用于快速检查服务是否响应
        return Result.success("服务状态正常", "Service is running");
    }
    
    /**
     * 测试接口
     * 
     * 这是一个简单的测试接口，用于：
     * - 验证API是否正常工作
     * - 测试网络连接
     * - 调试和开发阶段的功能验证
     * 
     * 注意：这个接口需要认证，因为它没有@PreAuthorize("permitAll()")注解
     * 
     * @return Result<String> 测试结果
     */
    @GetMapping("/test")
    public Result<String> test() {
        // 1. 返回测试成功信息
        // 如果能收到这个响应，说明：
        // - 服务正常运行
        // - JWT认证正常工作
        // - 用户已经通过认证
        return Result.success("测试成功", "Test OK");
    }
} 